package my.dao;

import java.sql.ResultSet;
import java.util.Date;
import java.util.List;
import java.util.Map;

/**
 * Dao是一个数据库访问对象，提供了对数据库的常用访问操作。
 * @version 3.0 
 * @author 夏冬琦
 *
 */
public interface Dao {
	

	/**
	 * 访问数据库的连接参数文件路径
	 */
	public static final String CONNECTION_SOURCE = "/db.properties";
	
	/**
	 * 连接数据库JDBC驱动类参数名称
	 */
	public static final String KEY_DRIVER_CLASS = "connection.driver_class";
	
	/**
	 * 连接数据库URL参数名称
	 */
	public static final String KEY_URL = "connection.url";
	
	/**
	 * 连接数据库用户名参数名称
	 */
	public static final String KEY_USERNAME = "connection.username";
	
	/**
	 * 连接数据库密码参数名称
	 */
	public static final String KEY_PASSWORD = "connection.password";
	
	/**
	 * 连接数据库是否使用事务参数名称
	 */
	public static final String KEY_TRANSACTION_USE = "transaction.use";
	
	
	
	/**
	 * 启用事务
	 */
	public static final int TX_USE_YES = 1;
	
	/**
	 * 禁用事务
	 */
	public static final int TX_USE_NO = 2;

	/**
	 * 开启事务
	 * @throws DaoException
	 */
	public abstract void beginTransaction() throws DaoException;

	/**
	 * 提交事务
	 * @throws DaoException
	 */
	public abstract void commitTransaction() throws DaoException;

	/**
	 * 回滚事务
	 * @throws DaoException
	 */
	public abstract void rollbackTransaction() throws DaoException;

	/**
	 * 关闭Dao对象，释放资源
	 */
	public abstract void close();

	/**
	 * 执行用于更新的sql语句，如update 、delete、insert和create等sql语句。
	 * @param sql sql语句
	 * @param args sql语句"?"占位符对应的参数值
	 * @return 返回影响行数，int类型。
	 * @throws DaoException
	 */
	public abstract int update(String sql, Object... args) throws DaoException;

	/**
	 * 执行用于查询的sql语句，既select语句,返回结果集（ResultSet）对象。
	 * @param sql sql语句
	 * @param args sql语句"?"占位符对应的参数值
	 * @return ResultSet类型，既结果集。
	 * @throws DaoException
	 */
	public abstract ResultSet query(String sql, Object... args)throws DaoException;
	
	/**
	 * 执行用于查询（select）sql语句，返回值为List集合，其元素为Map集合表示一条查询记录。这种Map集合的键为列标（全小写），值为列值。
	 * @param sql sql语句
	 * @param args sql语句"?"占位符对应的参数值
	 * @return List<Map<String, Object>>类型
	 * @throws DaoException
	 */
	public List<Map<String, Object>> queryMapList(String sql,Object... args) throws DaoException;	
	
	/**
	 * 执行用于查询（select）sql语句，返回值为List集合，其元素为数组对象表示一条查询记录，这种数组的每一个元素是一个列值。
	 * @param sql
	 * @param args
	 * @return 返回值为List集合，其元素为数组对象表示一条查询记录，这种数组的每一个元素是一个列值。
	 * @throws DaoException
	 */
	public List<Object[]> queryArrayList(String sql,Object... args) throws DaoException;
	
	
	/**
	 * 执行用于查询（select）sql语句，返回值为数组对象，其元素为JavaBean对象表示一条查询记录。
	 * @param beanClass
	 * @param sql
	 * @param args
	 * @return 返回值为数组对象，其元素为JavaBean对象表示一条查询记录。
	 * @throws DaoException
	 */
	public <T> Object[] queryBeanArray(Class<T> beanClass,String sql,Object... args) throws DaoException;
	
	/**
	 * 执行用于查询（select）sql语句，返回值为Object[][]对象，其元素为数组对象表示一条查询记录，这种数组的每一个元素是一个列值。
	 * @param sql
	 * @param args
	 * @return 返回值为Object[][]对象，其元素为数组对象表示一条查询记录，这种数组的每一个元素是一个列值。
	 * @throws DaoException
	 */
	public Object[][] queryArrayArray(String sql,Object... args) throws DaoException;
	
	/**
	 * 执行用于查询（select）sql语句，返回值为List集合，其元素由RowMapper对象的方法getObjectFromCurrentRow(ResultSet rs)的返回值确定。
	 * @param mapper
	 * @param sql
	 * @param args
	 * @return 返回值为List集合，其元素由RowMapper对象的方法getObjectFromCurrentRow(ResultSet rs)的返回值确定。
	 * @throws DaoException
	 */
	public <T> List<T> queryList(RowMapper<T> mapper, String sql,Object... args) throws DaoException;
	
	/**
	 * 执行用于查询（select）sql语句，返回值为JavaBean对象的List集合，JavaBean对象的类型由第一个参数beanClass确定。
	 * @param beanClass
	 * @param sql
	 * @param args
	 * @return 返回值为JavaBean对象的List集合，JavaBean对象的类型由第一个参数beanClass确定。
	 * @throws DaoException
	 */
	public <T> List<T> queryBeanList(Class<T> beanClass,String sql, Object... args) throws DaoException;
	
	/**
	 * 查询获得Integer对象的List集合。
	 * @param sql
	 * @param args
	 * @return 返回值为JavaBean对象的List集合，JavaBean对象的类型由第一个参数beanClass确定。
	 * @throws DaoException
	 */
	public List<Integer> queryIntegerList(String sql,Object... args) throws DaoException;
	
	/**
	 * 查询获得Long对象的List集合。
	 * @param sql
	 * @param args
	 * @return 返回Long对象的List集合。
	 * @throws DaoException
	 */
	public List<Long> queryLongList(String sql,Object... args) throws DaoException;
	
	/**
	 * 查询获得Float对象的List集合。
	 * @param sql
	 * @param args
	 * @return 返回Float对象的List集合。
	 * @throws DaoException
	 */
	public List<Float> queryFloatList(String sql,Object... args) throws DaoException;
	
	/**
	 * 执行用于查询（select）sql语句，获得Double对象的List集合。
	 * @param sql
	 * @param args
	 * @return 返回Double对象的List集合。
	 * @throws DaoException
	 */
	public List<Double> queryDoubleList(String sql,Object... args) throws DaoException;
	
	/**
	 * 执行用于查询（select）sql语句，获得Boolean对象的List集合。
	 * @param sql
	 * @param args
	 * @return 返回Boolean对象的List集合。
	 * @throws DaoException
	 */
	public List<Boolean> queryBooleanList(String sql,Object... args) throws DaoException;
	
	/**
	 * 执行用于查询（select）sql语句，获得java.util.Date的List集合。
	 * @param sql
	 * @param args
	 * @return 返回java.util.Date的List集合。
	 * @throws DaoException
	 */
	public List<Date> queryDateList(String sql,Object... args) throws DaoException;
	
	/**
	 * 执行用于查询（select）sql语句，获得字符串的List集合。
	 * @param sql
	 * @param args
	 * @return 返回字符串的List集合。
	 * @throws DaoException
	 */
	public List<String> queryStringList(String sql,Object... args) throws DaoException;
	
	/**
	 * 执行用于查询（select）sql语句，获得一个Map集合，该Map集合表示一条查询记录，键为列标（全小写），值为列值。
	 * @param sql
	 * @param args
	 * @return 返回Map集合，该Map集合表示一条查询记录，键为列标（全小写），值为列值。
	 * @throws DaoException
	 */
	public Map<String, Object> queryUniqueMap(String sql,Object... args) throws DaoException;
	
	/**
	 * 执行用于查询（select）sql语句，获得一个数组，该数组封装了一条记录，数组的每个元素对应一个列值。
	 * @param sql
	 * @param args
	 * @return 返回数组，该数组封装了一条记录，数组的每个元素对应一个列值
	 * @throws DaoException
	 */
	public Object[] queryUniqueArray(String sql,Object... args) throws DaoException;	
	
	/**
	 * 执行用于查询（select）sql语句，获得一个对象，该对象由RowMapper对象的方法getObjectFromCurrentRow(ResultSet rs)的返回值确定。。
	 * @param mapper
	 * @param sql
	 * @param args
	 * @return 返回封装一条记录的对象
	 * @throws DaoException
	 */
	public <T> T queryUniqueObject(RowMapper<T> mapper, String sql,Object... args) throws DaoException;	
	
	/**
	 * 执行用于查询（select）sql语句，获得一个JavaBean对象，JavaBean对象的类型由第一个参数beanClass确定。
	 * @param beanClass
	 * @param sql
	 * @param args
	 * @return 返回JavaBean对象，JavaBean对象的类型由第一个参数beanClass确定。
	 * @throws DaoException
	 */
	public <T> T queryUniqueBean(Class<T> beanClass, String sql,Object... args) throws DaoException;
	
	/**
	 * 执行用于查询（select）sql语句，获得一个Integer对象
	 * @param sql
	 * @param args
	 * @return 返回Integer对象
	 * @throws NoFoundRowException
	 * @throws DaoException
	 */
	public Integer queryInteger(String sql,Object... args) throws NoFoundRowException,DaoException;
	
	/**
	 * 执行用于查询（select）sql语句，获得一个Long对象
	 * @param sql
	 * @param args
	 * @return 返回Long对象
	 * @throws NoFoundRowException
	 * @throws DaoException
	 */
	public Long queryLong(String sql,Object... args) throws NoFoundRowException,DaoException;
	
	/**
	 * 执行用于查询（select）sql语句，获得一个Float对象
	 * @param sql
	 * @param args
	 * @return 返回Float对象
	 * @throws NoFoundRowException
	 * @throws DaoException
	 */
	public Float queryFloat(String sql,Object... args) throws NoFoundRowException,DaoException;
	
	/**
	 * 执行用于查询（select）sql语句，获得一个Double对象
	 * @param sql
	 * @param args
	 * @return 返回Double对象
	 * @throws NoFoundRowException
	 * @throws DaoException
	 */
	public Double queryDouble(String sql,Object... args) throws NoFoundRowException,DaoException;
	
	/**
	 * 执行用于查询（select）sql语句，获得一个Boolean对象
	 * @param sql
	 * @param args
	 * @return 返回Boolean对象
	 * @throws NoFoundRowException
	 * @throws DaoException
	 */
	public Boolean queryBoolean(String sql,Object... args) throws NoFoundRowException,DaoException;
	
	/**
	 * 执行用于查询（select）sql语句，获得一个java.util.Date对象
	 * @param sql
	 * @param args
	 * @return 返回java.util.Date对象
	 * @throws NoFoundRowException
	 * @throws DaoException
	 */
	public Date queryDate(String sql,Object... args) throws NoFoundRowException,DaoException;
	
	/**
	 * 执行用于查询（select）sql语句，获得一个字符串对象
	 * @param sql
	 * @param args
	 * @return 返回String对象
	 * @throws NoFoundRowException
	 * @throws DaoException
	 */	
	public String queryString(String sql,Object... args) throws NoFoundRowException,DaoException;

	/**
	 * 获取PreSQL对象
	 * @param sql
	 * @return 返回PreSQL对象
	 * @throws DaoException
	 */
	public abstract PreSQL preSQL(String sql) throws DaoException;

}